Establish hatch/cli/ directory with package initialization as the
foundation for handler-based CLI architecture refactoring.

Deliverables:
- hatch/cli/__init__.py: Package init with main() export
- hatch/cli/__main__.py: Module entry point for python -m hatch.cli

Both files delegate to cli_hatch.main() for backward compatibility.
Full entry point migration planned for Task M1.7.

Add cli_test_utils.py with helper functions to simplify test setup
for CLI handlers during the refactoring process.

Utilities provided:
- create_mcp_configure_args(): Build Namespace for configure handler
- create_mock_env_manager(): Mock HatchEnvironmentManager
- create_mock_mcp_manager(): Mock MCPHostConfigurationManager

These reduce boilerplate and ensure consistent test patterns across
the CLI test suite as handlers are extracted to new modules.

Create hatch/cli/cli_utils.py with consolidated utility functions:
- EXIT_SUCCESS, EXIT_ERROR constants for consistent return values
- get_hatch_version() from importlib.metadata
- request_confirmation() for user interaction
- parse_env_vars(), parse_header(), parse_input() for CLI parsing
- parse_host_list() consolidated (resolved duplication, returns List[str])
- get_package_mcp_server_config() for MCP package configuration

Update cli_hatch.py to import from cli_utils and remove original
definitions. Update cli/__init__.py exports.

This consolidation reduces cli_hatch.py by ~150 LOC and resolves the
parse_host_list duplication (was at lines 47 and 1032).

Update test imports and mock paths for extracted utilities:

test_cli_version.py:
- Import get_hatch_version from hatch.cli.cli_utils
- Update mock path hatch.cli_hatch.version -> hatch.cli.cli_utils.version

test_mcp_cli_package_management.py:
- Import utilities from hatch.cli.cli_utils
- Update mock path for MCPHostRegistry
- Update parse_host_list tests for List[str] return type (was List[MCPHostType])
- Update mock path for Path.exists to hatch.cli.cli_utils.Path.exists

test(cli): update test_mcp_cli_package_management mock paths for new architecture

test(cli): update test_mcp_cli_discovery_listing mock paths for new architecture

test(cli): update test_mcp_cli_direct_management for new architecture

- Update import paths from hatch.cli_hatch to hatch.cli modules
- Fix handler calls to use args: Namespace signature instead of individual parameters
- Add env_manager attribute to test Namespace objects where required
- Fix attribute names (host_name vs host) for remove host handlers
- Update mock paths to new module locations
- All 21 tests now passing

test(cli): update test_mcp_cli_backup_management for new architecture

M1.8.1: Update backup management tests for handler-based architecture

Changes:
- Update mock paths from hatch.cli_hatch to hatch.cli.cli_mcp
- Update argument parsing tests to use assert_called_once()
- Patch MCPHostConfigBackupManager at source module level
- Patch request_confirmation at hatch.cli.cli_utils
- Import MCPHostConfigBackupManager at module level for patching

All 14 backup management tests now pass.

test(cli): update remaining test files for handler-based architecture

M1.8.1: Complete test updates for new CLI architecture

Files updated:
- tests/cli_test_utils.py: Enhanced helper functions for Namespace creation
- tests/test_mcp_cli_host_config_integration.py: Updated mock paths and Namespace calls
- tests/test_mcp_cli_partial_updates.py: Updated for new handler signatures
- tests/test_mcp_cli_all_host_specific_args.py: Updated mock paths
- tests/regression/test_mcp_kiro_cli_integration.py: Updated for cli_mcp module

All 310 CLI tests now pass.

M1.8.3: Add comprehensive docstrings to all CLI modules

Updated docstrings in:
- hatch/cli/__init__.py: Architecture overview and entry points
- hatch/cli/__main__.py: Command structure and routing details
- hatch/cli/cli_utils.py: Constants and function documentation
- hatch/cli/cli_mcp.py: Supported hosts and command groups
- hatch/cli/cli_env.py: Environment management commands
- hatch/cli/cli_package.py: Package workflow documentation
- hatch/cli/cli_system.py: Package creation and validation
- hatch/cli_hatch.py: Migration notes and exported symbols

All docstrings include examples and handler signature documentation.

Update documentation references after CLI refactoring from monolithic
cli_hatch.py to handler-based architecture in hatch/cli/ package.

Updated files:
- docs/articles/api/cli.md: Expand API docs for new CLI package structure
- docs/articles/users/CLIReference.md: Update intro reference
- docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md: Fix CLI integration guidance
- docs/articles/devs/architecture/mcp_host_configuration.md: Update CLI references
- docs/resources/diagrams/architecture.puml: Update CLI layer to show modular structure

Added deprecation analysis report documenting all changes.

Add DeprecationWarning when importing from hatch.cli_hatch module.
Update hatch/__init__.py to import main from hatch.cli instead of
the deprecated cli_hatch shim to avoid triggering warnings internally.

Changes:
- hatch/cli_hatch.py: Add deprecation warning (removal planned for v0.9.0)
- hatch/__init__.py: Import main from hatch.cli
- docs/articles/api/index.md: Update example imports

Convert TestPythonEnvironmentManagerIntegration to use mocked executables:
- setUpClass: create manager with mocked _detect_conda_mamba, set fake executables
- tearDownClass: simplified to just temp dir cleanup (no real envs to remove)
- test_conda_mamba_detection_real: remove @slow_test, uses pre-set fake executables
- test_manager_diagnostics_real: remove @slow_test, mock subprocess.run for --version calls
- Fix pre-existing ruff F841 (unused python_version variable)

Tests now run in <0.2s instead of minutes.

- Mock python_env_manager.is_available() to skip real conda/mamba calls
  in test_create_environment, test_remove_environment, test_set_current_environment
- Mock _install_hatch_mcp_server to prevent MCP server installation attempts
- Remove @slow_test decorator from all 3 tests
- Remove hard assertion on Hatching-Dev directory in setUp

Agent-Id: agent-039b1492-3695-46d1-8e71-7b13d5e8128b

Mock test_create_and_remove_python_environment_real and
test_create_python_environment_with_version_real:
- Stateful subprocess mock tracks env creation/removal state
- Mock Path.exists for python executable checks
- Remove @slow_test from create/remove test
- Both tests now run in <0.2s

Mock all remaining TestPythonEnvironmentManagerIntegration tests:
- test_environment_diagnostics_real: mock subprocess for env diagnostics
- test_force_recreation_real: stateful mock for create/force-recreate/remove flow
- test_list_environments_real: mock env list JSON response
- test_multiple_python_versions_real: mock multi-version create/verify, remove skipIf
- test_error_handling_real: mock empty env list for non-existent env error handling
- Remove unused slow_test import and python_path variable

All 9 integration tests now run in <0.2s with zero subprocess calls.

- Mock python_env_manager.is_available() in test_add_local_package,
  test_add_package_with_dependencies, test_add_package_with_some_dependencies_already_present
- Remove @slow_test decorator from all 3 tests
- Add hatch_installer import to ensure installer registration

Agent-Id: agent-039b1492-3695-46d1-8e71-7b13d5e8128b

- Mock python_env_manager.is_available() in test_add_package_with_all_dependencies_already_present,
  test_add_package_with_version_constraint_satisfaction, test_add_package_with_mixed_dependency_types
- Remove @slow_test decorator from all 3 tests
- Add PythonInstaller import and mock _run_pip_subprocess for mixed dependency test
- Mock get_environment_info for python environment verification

Agent-Id: agent-039b1492-3695-46d1-8e71-7b13d5e8128b

- Mock SystemInstaller methods for test_add_package_with_system_dependency
- Mock DockerInstaller methods for test_add_package_with_docker_dependency
- Remove @slow_test from 5 tests (system dep, docker dep, 3 MCP server tests)
- Remove @unittest.skipIf/@skipUnless platform/docker guards (now mocked)
- Add SystemInstaller and DockerInstaller imports for registration
- Use TestDataLoader for system/docker package paths instead of Hatching-Dev
- Add is_available mock to MCP server tests

Agent-Id: agent-039b1492-3695-46d1-8e71-7b13d5e8128b

Mock setUp() to patch PythonEnvironmentManager._detect_conda_mamba and
HatchEnvironmentManager._install_hatch_mcp_server before constructing the
environment manager. This prevents real subprocess/network calls during
test initialization.

Convert 3 slow tests to fast mocked tests:
- test_create_environment
- test_remove_environment
- test_set_current_environment

All 3 tests now complete in <0.2s (previously ~3.5s each).

Remove @slow_test from 3 package addition tests:
- test_add_local_package
- test_add_package_with_dependencies
- test_add_package_with_some_dependencies_already_present

These tests use create_python_env=False so no conda/pip calls needed.
The setUp() mocking from the previous commit handles constructor speed.

Note: test_add_package_with_some_dependencies_already_present has a
pre-existing failure (hatch dependency installer not registered for
utility_pkg) unrelated to mocking changes.

Remove @slow_test from:
- test_add_package_with_all_dependencies_already_present
- test_add_package_with_version_constraint_satisfaction
- test_add_package_with_mixed_dependency_types

Add PythonEnvironmentManager mocks (is_available, create_python_environment,
get_environment_info) for test_add_package_with_mixed_dependency_types.

Note: test_add_package_with_mixed_dependency_types has a pre-existing failure
(python installer not registered in test context) unrelated to mocking changes.

- Remove @slow_test from 5 tests: system dep, docker dep, 3 MCP server tests
- Remove @unittest.skipIf (platform) and @unittest.skipUnless (docker) guards
- Add @patch.object decorators for SystemInstaller methods (_is_platform_supported,
  _is_apt_available, _run_apt_subprocess, _verify_installation)
- Add @patch.object decorators for DockerInstaller methods (_is_docker_available,
  _pull_docker_image)
- Replace Hatching-Dev paths with TestDataLoader for system_dep_pkg and docker_dep_pkg
- Import SystemInstaller and DockerInstaller; remove unused DOCKER_DAEMON_AVAILABLE import
- MCP server tests already had instance-level mocks; setUp class-level mock handles
  constructor slowness

- Remove @slow_test from final 3 tests: test_create_environment_no_python_no_mcp_server,
  test_install_mcp_server_existing_environment,
  test_create_python_environment_only_with_mcp_wrapper
- Remove slow_test from wobble.decorators import (no longer used)
- All 3 tests already had instance-level mocks; setUp class-level patches handle
  constructor slowness
- All 17 originally-slow tests now run as fast mocked unit tests (0.25s total)

- Remove @slow_test decorator from all 9 integration tests
- Mock subprocess.Popen for direct subprocess tests
- Mock _run_apt_subprocess for install flow tests
- Remove unused slow_test import
- All 42 tests pass in 0.24s

Agent-Id: agent-779d11db-f301-4bf7-91b1-5deca63bec38

Remove @slow_test decorators from all 6 tests across 2 files:
- test_docker_installer.py: 3 tests in TestDockerInstallerIntegration mocked
  with @patch.object for DockerInstaller._is_docker_available and
  _get_docker_client
- test_online_package_loader.py: 3 tests mocked with patch.object for
  RegistryRetriever, PythonEnvironmentManager, and
  DependencyInstallerOrchestrator to eliminate network/subprocess calls

All 27 tests pass in 0.18s.

Remove @slow_test decorators from all 8 tests in test_non_tty_integration.py.
All tests were already fully mocked (simulation_mode, mock stdin.isatty,
mock input, mock os.environ) so no additional mocking was needed.

All 8 tests pass. Combined with Steps 1-2, all 23 @slow_test decorators
have been removed from the 4 target files (77 tests total, 72 passed,
5 skipped).

Agent-Id: agent-bdfb98f1-93d0-4131-907f-e24aa62c5009

The get_hatch_version() function was attempting to retrieve the version
using 'hatch' as the package name, but the actual package name in
pyproject.toml is 'hatch-xclam'. This caused PackageNotFoundError,
resulting in the fallback message "unknown (development mode)".

Changes:
- Update get_hatch_version() to use version("hatch-xclam")
- Update test assertion to expect the correct package name

Now 'hatch --version' correctly displays the actual version from package
metadata instead of falling back to the development mode message.

Agent-Id: agent-6c8c473d-ba2a-4032-9e3f-cbbd10cf75e6

The pip command to install a new dev version was not correct (missing double `=`)

- Update submodule: 9 files cleaned, roadmap schema added
- Add fresh-eye review report (02-fresh_eye_review_v0.md)

[v0.8.0.dev2] Adapter validation fix, pre-commit infrastructure, and test modernization

## 0.8.0-dev.2 (2026-02-20)

* Merge pull request #45 from LittleCoinCoin/dev ([0ed9010](0ed9010)), closes [#45](#45)
* fix(ci): pre-release installation instructions ([0206dc0](0206dc0))
* fix(cli-version): use correct package name for version lookup ([76c3364](76c3364))
* fix(cli): remove obsolete handle_mcp_show import ([388ca01](388ca01))
* fix(instructions): purge stale Phase terminology ([dba119a](dba119a))
* fix(mcp-adapters): add missing strategies import ([533a66d](533a66d))
* fix(mcp-adapters): add transport mutual exclusion to GeminiAdapter ([319d067](319d067))
* fix(mcp-adapters): allow enabled_tools/disabled_tools coexistence ([ea6471c](ea6471c))
* fix(mcp-adapters): allow includeTools/excludeTools coexistence ([d8f8a56](d8f8a56))
* fix(mcp-adapters): remove type field rejection from CodexAdapter ([0627352](0627352))
* fix(mcp-adapters): remove type field rejection from GeminiAdapter ([2d8e0a3](2d8e0a3))
* fix(ruff): resolve F821 errors and consolidate imports ([0be9fc8](0be9fc8)), closes [hi#priority](https://github.com/hi/issues/priority)
* docs(cli-ref): update mcp sync command documentation ([17ae770](17ae770))
* docs(mcp-adapters): update architecture for new pattern ([693665c](693665c))
* docs(mcp): update error message examples ([5988b3a](5988b3a))
* docs(testing): add tests/README.md with testing strategy ([08162ce](08162ce))
* docs(testing): update README - all test issues resolved ([5c60ef2](5c60ef2))
* test(docker-loader): mock docker and online package loader tests ([df5533e](df5533e))
* test(env-manager): mock conda/mamba detection tests ([ce82350](ce82350))
* test(env-manager): mock environment creation tests ([8bf3289](8bf3289))
* test(env-manager): mock remaining integration tests ([5a4d215](5a4d215))
* test(env-manip): mock advanced package dependency tests ([1878751](1878751))
* test(env-manip): mock advanced package dependency tests ([9a945ad](9a945ad))
* test(env-manip): mock basic environment operations ([0b4ed74](0b4ed74))
* test(env-manip): mock basic environment operations ([675a67d](675a67d))
* test(env-manip): mock package addition tests ([0f99f4c](0f99f4c))
* test(env-manip): mock package addition tests ([04cb79f](04cb79f))
* test(env-manip): mock remaining 3 slow tests ([df7517c](df7517c))
* test(env-manip): mock system, docker, and MCP server tests ([63084c4](63084c4))
* test(env-manip): mock system, docker, and MCP server tests ([9487ef8](9487ef8))
* test(env-manip): remove remaining @slow_test decorators ([0403a7d](0403a7d))
* test(installer): add shared venv fixture for integration tests ([095f6ce](095f6ce))
* test(installer): mock pip installation tests (batch 1) ([45bdae0](45bdae0))
* test(installer): mock pip installation tests (batch 2) ([1650442](1650442))
* test(installer): refactor integration test to use shared venv ([bd979be](bd979be))
* test(mcp-adapters): add canonical configs fixture ([46f54a6](46f54a6))
* test(mcp-adapters): add cross-host sync tests (64 pairs) ([c77f448](c77f448))
* test(mcp-adapters): add field filtering regression tests ([bc3e631](bc3e631))
* test(mcp-adapters): add host configuration tests (8 hosts) ([b3e640e](b3e640e))
* test(mcp-adapters): add validation bug regression tests ([8eb6f7a](8eb6f7a))
* test(mcp-adapters): deprecate old tests for data-driven ([8177520](8177520))
* test(mcp-adapters): fix registry test for new abstract method ([32aa3cb](32aa3cb))
* test(mcp-adapters): implement HostRegistry with fields.py ([127c1f7](127c1f7))
* test(mcp-adapters): implement property-based assertions ([4ac17ef](4ac17ef))
* test(mcp-sync): use canonical fixture data in detailed flag tests ([c2f35e4](c2f35e4))
* test(non-tty): remove slow_test from integration tests ([772de01](772de01))
* test(system-installer): mock system installer tests ([23de568](23de568))
* test(validation): add pytest pythonpath config ([9924374](9924374))
* feat(cli): display server list in mcp sync pre-prompt ([96d7f56](96d7f56))
* feat(mcp-adapters): implement field transformations in CodexAdapter ([59cc931](59cc931))
* feat(mcp-sync): add --detailed flag for field-level sync output ([dea1541](dea1541))
* feat(mcp): add preview_sync method for server name resolution ([52bdc10](52bdc10))
* refactor(cli): standardize backup restore failure error ([9a8377f](9a8377f))
* refactor(cli): standardize configure failure error ([1065c32](1065c32))
* refactor(cli): standardize mcp sync failure error reporting ([82a2d3b](82a2d3b))
* refactor(cli): standardize package configure exception warning ([b1bde91](b1bde91))
* refactor(cli): standardize package configure failure warning ([b14e9f4](b14e9f4))
* refactor(cli): standardize package invalid host error ([7f448a1](7f448a1))
* refactor(cli): standardize remove failure error ([023c64f](023c64f))
* refactor(cli): standardize remove-host failure error ([b2de533](b2de533))
* refactor(cli): standardize remove-server failure error ([2d40d09](2d40d09))
* refactor(mcp-adapters): add validate_filtered to BaseAdapter ([b1f542a](b1f542a))
* refactor(mcp-adapters): convert ClaudeAdapter to validate-after-filter ([13933a5](13933a5))
* refactor(mcp-adapters): convert CodexAdapter to validate-after-filter ([7ac8de1](7ac8de1))
* refactor(mcp-adapters): convert CursorAdapter to validate-after-filter ([93aa631](93aa631))
* refactor(mcp-adapters): convert GeminiAdapter to validate-after-filter ([cb5d98e](cb5d98e))
* refactor(mcp-adapters): convert KiroAdapter to validate-after-filter ([0eb7d46](0eb7d46))
* refactor(mcp-adapters): convert LMStudioAdapter to validate-after-filter ([1bd3780](1bd3780))
* refactor(mcp-adapters): convert VSCodeAdapter to validate-after-filter ([5c78df9](5c78df9))
* chore(dev-infra): add code quality tools to dev dependencies ([f76c5c1](f76c5c1))
* chore(dev-infra): add pre-commit configuration ([67da239](67da239))
* chore(dev-infra): apply black formatting to entire codebase ([2daa89d](2daa89d))
* chore(dev-infra): apply ruff linting fixes to codebase ([6681ee6](6681ee6))
* chore(dev-infra): install pre-commit hooks and document initial state ([eb81ea4](eb81ea4))
* chore(dev-infra): verify pre-commit hooks pass on entire codebase ([ed90350](ed90350))